Release 10.1A: OpenEdge Development:
Java Open Clients

Common methods

The Open Client interface provides common methods which provide information about the current state of Java proxy AppObjects, SubAppObjects, and ProcObjects, with respect to their connection to the application service. The section lists these methods and describes the information they provide. This information might differ based on whether the application service is run session-managed or session-free. (For an overview of session models, see OpenEdge Development: Open Client Introduction and Programming .)

Cancel all requests

The following method stops or cancels any outstanding requests to the AppServer by this object or one that shares its connection:

Syntax

public void _cancelAllRequests()

The _cancelAllRequests() method is most useful for multi-threaded clients.

This method throws a com.progress.open4gl.Open4GLException.

AppObjects, SubAppObjects, and ProcObjects have a _cancelAllRequests() method that a client can call to:

Terminate a request that was initiated by any object in the proxy and is running (normally during a long execution).
Cancel any requests that might be queued for execution.
Close any open ResultSets.

When a client invokes a proxy method, the result is a request to the AppServer. The request itself can be in one of three states. Also, note that when the method completes and returns control to the application, the request still can be active if there is an open output ResultSet (that is, the connection is in a STREAMING state).

The three request states are:

QUEUED — The connection is busy with a request from another thread. The current request is queued until the connection becomes available.
RUNNING — The current request is being run on the connection, and the connection is in the RUNNING state.
STREAMING — The current request is transmitting records over the connection, and the connection is in the STREAMING state.

The _cancelAllRequests() method operates on a request according to its state as follows:

QUEUED — Cancels the request and throws an exception.
RUNNING — Forwards a STOP request to the 4GL interpreter on the AppServer, which handles it according to normal 4GL STOP condition rules.
STREAMING — Initiates the close of any currently open output ResultSets, but does not call the close() method. You must then execute the close() method on all affected output ResultSets, to complete the closure. For large ResultSets, this is more efficient than using the close() method alone. For more information on the close() method, see Appendix C, "Passing Temp-tables as SQL ResultSet Parameters".

If there are no requests in the above states when you run _cancelAllRequests(), the method has no effect.

Connection ID

The _getConnectionId() method is most often used to identify entries in AppServer log files.

For session-managed applications, the following method returns a string containing a unique identifier for this connection.

For session-free applications, the following method returns a string containing a unique identifier for the connection most recently used by the current thread:

Syntax

public String _getConnectionId()

The _getConnectionId() method throws a com.progress.open4gl.Open4GLException if the Application Service is not connected.

Streaming

For session-managed applications, the _isStreaming() method determines if the method most recently run on any thread is currently streaming an output result set.

For session-free applications, the _isStreaming() method determines if the method most recently run on the current thread is currently streaming an output result set. This state information cannot be retrieved by another thread.

This method returns true if there is an open OUTPUT TABLE or TABLE-HANDLE for this connection:

Syntax

public boolean _isStreaming()

The _isStreaming() method throws a com.progress.open4gl.Open4GLException. For more information on streaming, see the information on output ResultSet parameters in Appendix C "Passing Temp-tables as SQL ResultSet Parameters."

Procedure return string

For session-managed applications, the _getProcReturnString() method retrieves the return value of the method most recently run on any thread.

For session-free applications, the _getProcReturnString() method retrieves the return value of the method most recently run on the current thread. The return value cannot be retrieved by another thread.

This method returns the current value of the AppServer RETURN-VALUE function:

Syntax

public String _getProcReturnString()

For more information on handling return values, see the "Handling return values" section.

Release

The _release() method makes this object unavailable for further use:

Syntax

public void _release()

If you execute _release() on the last available proxy object that shared a particular connection, the client disconnects the AppServer. If you execute _release() on a ProcObject, the associated persistent procedure on the AppServer is deleted.

Request ID

For session-managed applications, the _getRequestId() method returns a unique string identifying the request most recently run on any thread.

For session-free applications, the _getRequestId() method returns a unique string identifying the request most recently run on the current thread. The Request ID cannot be retrieved by another thread.

This method throws a com.progress.open4gl.Open4GLException if the session is not available:

Syntax

public String _getRequestId()

SSL subject name

The _getSSLSubjectName() method provides the SSL server's subject name that is obtained from its validated digital certificate. This method throws a com.progress.open4gl.Open4GLException if the session is not available:

Syntax

public String _getSSLSubjectName()